<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>3.2.&nbsp;&lt;emmajava&gt;: instrumenting Java classes
on-the-fly</title><link href="../skin/css/doc.css" rel="stylesheet" type="text/css"><meta content="DocBook XSL Stylesheets V1.66.1" name="generator"><link rel="start" href="userguide.html" title="EMMA User Guide"><link rel="up" href="ar01s03.html" title="3.&nbsp;Getting Started (ANT)"><link rel="prev" href="ar01s03.html" title="3.&nbsp;Getting Started (ANT)"><link rel="next" href="ar01s03s03.html" title="3.3.&nbsp;Offline mode: separating instrumentation and execution"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">3.2.&nbsp;<span><b class="command">&lt;emmajava&gt;</b></span>: instrumenting Java classes
on-the-fly</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ar01s03.html"><img src="../images/prev.gif" alt="Prev"></a>&nbsp;</td><th align="center" width="60%">3.&nbsp;Getting Started (<span class="emphasis"><em>ANT</em></span>)</th><td align="right" width="20%">&nbsp;<a accesskey="n" href="ar01s03s03.html"><img src="../images/next.gif" alt="Next"></a></td></tr></table><hr></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N101C4"></a>3.2.&nbsp;<span><b class="command">&lt;emmajava&gt;</b></span>: instrumenting Java classes
on-the-fly</h3></div></div></div><p>Let's create a simple ANT build file for the source code in
<tt class="filename">examples/src</tt>. Add this after EMMA task
definitions:</p><pre class="programlisting">
  &lt;!-- root directory for the example source code: --&gt; 
  &lt;property name="src.dir" value="${basedir}/src" /&gt;

  &lt;!-- javac class output directory: --&gt;
  &lt;property name="out.dir" value="${basedir}/out" /&gt;

  &lt;target name="init" &gt;
    &lt;mkdir dir="${out.dir}" /&gt;
    &lt;path id="run.classpath" &gt;
      &lt;pathelement location="${out.dir}" /&gt;
    &lt;/path&gt;
  &lt;/target&gt;

  &lt;target name="compile" depends="init" description="compiles the example source code" &gt;
    &lt;javac debug="on" srcdir="${src.dir}" destdir="${out.dir}" /&gt;
  &lt;/target&gt;

  &lt;target name="run" depends="init, compile" description="runs the examples" &gt;
    &lt;java classname="Main"
          classpathref="run.classpath"
    &gt;
    &lt;/java&gt;
  &lt;/target&gt;</pre><p>You can now compile and run the example:</p><pre class="screen">
&gt;ant run
Buildfile: build.xml

init:
    [mkdir] Created dir: .../examples/out

compile:
    [javac] Compiling 4 source files to .../examples/out

run:
     [java] main(): running doSearch()...
     [java] main(): done

BUILD SUCCESSFUL
Total time: 5 seconds</pre><p><span><b class="command">&lt;emmajava&gt;</b></span> is an EMMA extension of ANT
stock <span><b class="command">&lt;java&gt;</b></span> task that is an ANT adapter to the
same instrumenting application runner as used by EMMA
<span><b class="command">emmarun</b></span> command line tool. Upgrading your build to do
code coverage on-the-fly is very easy: just replace &lt;java&gt; tags with
&lt;emmajava&gt; tags for tasks that run your application or test cases.
Don't worry, your build is not now in a permanent coverage-enabled mode:
<span><b class="command">&lt;emmajava&gt;</b></span> becomes a pass-through to the normal
<span><b class="command">&lt;java&gt;</b></span> when its <tt class="option">enabled</tt> attribute
is set to <tt class="option">false</tt>:</p><pre class="programlisting">
  &lt;target name="emma" description="turns on EMMA's on-the-fly instrumentation mode" &gt;
    &lt;property name="emma.enabled" value="true" /&gt;
  &lt;/target&gt;

  &lt;target name="run" depends="init, compile" description="runs the examples" &gt;
    &lt;emmajava enabled="${emma.enabled}" libclasspathref="emma.lib" 
              classname="Main"
              classpathref="run.classpath"
    &gt;
    &lt;/emmajava&gt;
  &lt;/target&gt;</pre><p>Now, whenever you insert <span><b class="command">emma</b></span> before any run
targets on ANT's command line, you enable on-the-fly coverage
instrumentation and reporting (but ANT commands without <span><b class="command">emma</b></span>
continue to function as before):</p><pre class="screen">
&gt;ant emma run
Buildfile: build.xml

emma:

init:
    [mkdir] Created dir: .../examples/out

compile:
    [javac] Compiling 4 source files to .../examples/out

run:
 [emmajava] main(): running doSearch()...
 [emmajava] main(): done
 [emmajava] EMMA: writing [txt] report to [.../coverage.txt] ...

BUILD SUCCESSFUL
Total time: 7 seconds</pre><p>The default text coverage report is generated in the current
directory:</p><pre class="screen">
[EMMA v2.0.3611 report, generated Sun Jan 11 14:18:08 CST 2004]
-------------------------------------------------------------------------------
OVERALL COVERAGE SUMMARY:

[class, %]      [method, %]     [block, %]      [line, %]       [name]
100% (3/3)      100% (7/7)      95%  (116/122)  100% (29/29)    all classes

OVERALL STATS SUMMARY:

total packages: 2
total classes:  3
total methods:  7
total executable files: 3
total executable lines: 29

COVERAGE BREAKDOWN BY PACKAGE:

[class, %]      [method, %]     [block, %]      [line, %]       [name]
100% (2/2)      100% (4/4)      91%  (64/70)    100% (18/18)    search
100% (1/1)      100% (3/3)      100% (52/52)    100% (11/11)    default package
-------------------------------------------------------------------------------</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Other report types</h3><p>By default, <span><b class="command">&lt;emmajava&gt;</b></span> generates a
plain-text report only. The default report's depth is <tt class="option">all</tt>
which means to show the overall coverage summary followed by breakdown by
package. You can increase the default depth to include package and source
file summaries. This and many other aspects of EMMA report generation can be
configured using various attributes and nested elements that
<span><b class="command">&lt;emmajava&gt;</b></span> adds to <span><b class="command">&lt;java&gt;</b></span>.
These extensions only take effect when the task is in enabled state and have
no impact on the build otherwise. See <a class="olink" href="../reference/ch03.html">Chapter3, EMMA Property Reference</a>
in the reference manual for full details on EMMA configuration.</p></div><p><span><b class="command">&lt;emmajava&gt;</b></span> application runner uses an
instrumenting classloader to add bytecode instrumentation to Java classes as
they are being loaded by the JVM. For efficiency reasons,
<span><b class="command">&lt;emmajava&gt;</b></span> does not scan your entire classpath
before it starts running. This has the side effect of only reporting on the
classes that got loaded by the application. If your intent is to base
coverage metrics on the full set of classes in the classpath, you can set
<tt class="option">fullmetadata</tt> task attribute to <tt class="option">true</tt>. Here
is an example that also adds some extra reports and makes sure the HTML
report generator has access to the source code by setting
<tt class="option">sourcepath="${src.dir}"</tt>:</p><pre class="programlisting">
  &lt;!-- output directory used for EMMA coverage reports: --&gt;
  &lt;property name="coverage.dir" value="${basedir}/coverage" /&gt;

  &lt;target name="run" depends="init, compile" description="runs the examples" &gt;
    &lt;emmajava enabled="${emma.enabled}" libclasspathref="emma.lib" 
              fullmetadata="yes" sourcepath="${src.dir}"
              classname="Main"
              classpathref="run.classpath"
    &gt;
      &lt;txt outfile="${coverage.dir}/coverage.txt" /&gt;
      &lt;xml outfile="${coverage.dir}/coverage.xml" /&gt;
      &lt;html outfile="${coverage.dir}/coverage.html"  /&gt;
    &lt;/emmajava&gt;
  &lt;/target&gt;
</pre><p>Although this was not the case with this tutorial's sample code,
chances are your application has third-party library dependencies and you
are not interested in their coverage metrics. There are two ways to handle
this with <span><b class="command">&lt;emmajava&gt;</b></span>:</p><div class="calloutlist"><table summary="Callout list" border="0"><tr><td align="left" valign="top" width="5%"><a name="C0"></a><a href="#C0-co"><img border="0" alt="1" src="../images/callouts/1.png"></a> </td><td align="left" valign="top"><p>List libraries in the JVM's
classpath, not <span><b class="command">&lt;emmajava&gt;</b></span>'s classpath. You do that
by adding them to <span><b class="command">&lt;emmajava&gt;</b></span>'s
<tt class="option">emmaclasspath</tt> attribute instead of the usual
<tt class="option">classpath</tt>:

<pre class="programlisting">
    &lt;emmajava enabled="${emma.enabled}" libclasspathref="allmylibs.path"<a name="C0-co" href="ar01s03s02.html#C0"><img border="0" alt="1" src="../images/callouts/1.png"></a> 
              classname="Main"
              classpathref="run.classpath"
    &gt;
    &lt;/emmajava&gt;</pre>
     </p></td></tr><tr><td align="left" valign="top" width="5%"><a name="C1"></a><a href="#C1-co"><img border="0" alt="1" src="../images/callouts/1.png"></a> </td><td align="left" valign="top"><p>Use a coverage filter to
make sure that only the classes of interest are instrumented:

<pre class="programlisting">
    &lt;emmajava enabled="${emma.enabled}" libclasspathref="emma.lib" 
              classname="Main"
              classpathref="run.classpath"
    &gt;
      <a name="C1-co" href="ar01s03s02.html#C1"><img border="0" alt="1" src="../images/callouts/1.png"></a>&lt;filter includes="Main, search.*" /&gt;
    &lt;/emmajava&gt;</pre>

      </p></td></tr></table></div><p>If these techniques are not sufficient (e.g., you need to
exclude testcases from coverage and they are in the same Java packages as
the application code and do not follow a sensible naming pattern), you can
always switch to offline instrumentation as described next. Offline
instrumentation does not keep everything in memory and ultimately gives you
much more control over what gets instrumented.</p><p>To summarize, an existing <tt class="filename">build.xml</tt> can be
converted to use EMMA's on-the-fly instrumentation mode by following these
steps:
	<div class="orderedlist"><ol type="1" compact="compact"><li><p>add EMMA task definitions</p></li><li><p>replace the necessary invocations of
<span><b class="command">&lt;java&gt;</b></span> with
<span><b class="command">&lt;emmajava&gt;</b></span></p></li><li><p>configure coverage paths and inclusion/exclusion
filters</p></li><li><p>configure coverage reports</p></li><li><p>make sure there is a way to turn coverage instrumentation
off</p></li></ol></div>
</p><p><b>Futher reading.&nbsp;</b>This has been a quick intro to EMMA's on-the-fly ANT
instrumentation mode. For further details see <a class="olink" href="../reference/ch02s02.html">Section2, &lt;emmajava&gt;/emmarun</a> in the reference manual.</p></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ar01s03.html"><img src="../images/prev.gif" alt="Prev"></a>&nbsp;</td><td align="center" width="20%"><a accesskey="u" href="ar01s03.html"><img src="../images/up.gif" alt="Up"></a></td><td align="right" width="40%">&nbsp;<a accesskey="n" href="ar01s03s03.html"><img src="../images/next.gif" alt="Next"></a></td></tr><tr><td valign="top" align="left" width="40%">3.&nbsp;Getting Started (<span class="emphasis"><em>ANT</em></span>)&nbsp;</td><td align="center" width="20%"><a accesskey="h" href="userguide.html"><img src="../images/home.gif" alt="Home"></a></td><td valign="top" align="right" width="40%">&nbsp;3.3.&nbsp;Offline mode: separating instrumentation and execution</td></tr></table></div></body></html>